The Datafile PD-CD 1 Issue 2/PDCD-1 - Issue 02.iso/_utilities/utilities/001/menuutils/MenuDoc

Text File | 1993-01-23 | 10KB | 255 lines

    Documentation for the MenuUtils module v.0.10

                     ⌐ Petrov Software 1992




                           Introduction

This module is mainly intended for people who write RISC OS
applications in BBC BASIC. It can save programmer from the need to
write his own procedures in BASIC for handling menus. MenuUtils module
can perform all the work needed to create, edit, display and decode
menus. The module is very simple in use and is ideal for creating
simple menus. On the other hand module's advanced features allows
easily create and manipulate even very complex multi-level dynamic
menus.



                  What does MenuUtils do ?

The MenuUtils module is not the extension to the Window Manager and it
doesn't provide any extra feature. The module only provides a
convenient interface for the programmer to Window Manager's menu
system. The module has a collection of SWIs to do all the low level
work concerned with direct accesses to menu data structures, memory
allocation, etc. It saves the author of application program from the
need to do this routine work himself.

MenuUtils provides mechanism of item handlers. It allows to attach
individual handler to each menu item. In case of BBC BASIC the handler
may be simply a BASIC function. When menu item is selected the
corresponding item handler may be invoked automatically. This feature
saves the programmer from the need to decode the list of menu
selections. During program development the use of individual item
handlers simplifies the process of menu modification. You can freely
rearrange menu items without the need to make any changes in other
parts of the program. There is an example in the end of this text
which illustrates the use of item handlers in BASIC programs.

MenuUtils automatically allocates memory to hold menu data structures.
And also it takes care about  appearance of menus on screen by forcing
them to be in standard RISC OS style.



                      Technical details

Module MenuUtils may be used only by programs which are WIMP tasks.
Special SWI MenuUtil_Initialise is provided to register the program as
MenuUtils client. MenuUtil_Initialise must be called after
Wimp_Initialise has been called and before any other call to MenuUtils
module is made.

All menus created by MenuUtils are kept in RMA. So you have no need to
reserve memory for them. On exit from your program all the memory will
be automatically returned to RMA.

Single MenuUtils module can handle menus for several WIMP tasks.

Internal format of menu data structures created by the module is the
same as described in RISC OS 2 PRM. So it is possible to combine menus
created by MenuUtils with other menus. To find out address of menu
data structure you can use SWI MenuUtil_Info.



                        Menu handles

Menu consists of menu title and one or more menu items. Each menu and
each menu item created with MenuUtils gets unique handle. You can use
this handle to refer to particular menu or menu item.

The use of unique handles for each menu item instead of absolute
addresses or positions in menu gives additional flexibility in
manipulation with menu data structure. It allows for example insert
and delete menu items.

MenuUtils always remembers the handle used in last operation. This
handle is called current handle and it will be used as default in the
next operation. This is especially convenient when calls to the module
are made from BASIC with SYS command.



                        Menu creation

To start new menu you must call MenuUtil_New. Then you may add to it
any number of menu items. To add new item you must call MenuUtil_Add.
Menu always is ready to be displayed on screen and you have no need to
specially inform the module when you have added the last item to the
menu.

By default all new items are added to the end of menu. If you want to
insert new item in the middle of menu then you must specify the handle
of the item before which you want to insert the new item.

All menu flags in added items are cleared. Colours and dimensions are
in standard RISC OS style. Width of menu is adjusted automatically.

In order to construct multi-level menu tree you have to connect some
menu items with submenus or with dialog boxes. MenuUtils provides
special SWI to link menu item with submenu. This SWI also allows you
to link menus created by MenuUtils with other menus.



                      Menu modification

You can in any moment change menu title string as well as the text of
menu items. You can also change foreground and background colours of
menu items.

Menu item has a number of flags which control its appearance and
behaviour. The flags are tick, fade, dots, submenu, writable and
message. Special SWIs are provided to set or clear each menu flag. As
a special case when you are making menu item writable you can also
specify buffer size and optional validation string.

You can delete single menu item or the whole menu with
MenuUtil_Delete. You can also recursively delete the whole menu
subtree connected with the deleted item or with the deleted menu.


                   Displaying menu on screen

According to RISC OS rules you must display menu on screen when user
clicks with Menu button over one of your windows or iconbar icon. To
find out where to display the menu you have to perform some
calculations. MenuUtils provides a SWI MenuUtil_Show which will
perform all necessary calculations for you and open menu in the right
screen position according to RISC OS standards.

Special SWI is provided to display submenu in reply to
Message_MenuWarning.



               Item handlers and menu decoding

The mechanism of item handlers allows to link each menu item with
individual item handler. The handler may be invoked automatically and
you have no need to decode the list of selections in order to take the
appropriate action.

During the call to "MenuUtil_Initialise" you must specify
initialisation type. Initialisation type defines the interpretation of
item handlers and can be "BASIC" or "machine code" (latter is not
supported in current version). In case of "BASIC" the item handlers
are assumed to be the BASIC functions and in case of "machine code" -
ARM subroutines. If you want to attach a handler to menu item you must
pass the pointer to the name of BASIC function or respectively the
address of the ARM subroutine to MenuUtil_Add.

After user selection the corresponding item handler will be found by
"MenuUtil_Decode". To invoke the handler you have to call either the
BASIC function or the ARM subroutine depending on initialisation type.



                        Other features

Many applications use standard menu allowing user to select a colour
from standard desktop colours. MenuUtils provides a special SWI
"MenuUtil_ColourMenu" which creates such colour setting menu.



                      Application notes

This example illustrates the use of menu item handlers in programs in
BBC BASIC. Lets consider simple menu consisting of single item.

            +----------------+
            |                |
            |  Simple menu   |
            |                |
            +----------------+
            |  Item#1        |
            +----------------+

To create this menu we must call "MenuUtil_New" and to add an item -
"MenuUtil_Add".

 SYS "MenuUtil_New",,"Simple menu"
 SYS "MenuUtil_Add",,"Item#1","func1"

- here "Simple menu" is menu title, "Item#1" - item text and "func1" -
name of the item handler. The name of the handler is "func1" so we
must have a function with the name "FNfunc1".

 DEF FNfunc1
 ...
 =TRUE

Then we organize the main Wimp_Poll loop in the following way.

 DIM q% &100
 REPEAT SYS "Wimp_Poll",,q% TO reason%
   CASE reason% OF
     ...
     REM Mouse click
     WHEN 6
            IF q%!8=2 THEN SYS "MenuUtil_Show",,q%

     REM Menu selection
     WHEN 9
            SYS "MenuUtil_Decode",,q% TO handler%
            IF handler% THEN
              handler$="FN"+$handler%
              IF EVAL handler$
            ENDIF
     ...
   ENDCASE
 UNTIL FALSE

If the user clicks with Menu button we will call "MenuUtil_Show" to
display menu on screen. If user selects something from our menu we
will call "MenuUtil_Decode" to find out corresponding item handler.
Variable handler% will contain pointer to the handler name. In our
example if user will select item "Item#1" variable handler% will point
to string "func1". The full name of the handler will be
"FN"+$handler%. And EVAL statement is used to call it.


------------------------------------------------------------------------
                    Notes from the author


MenuUtils is freeware software. Everybody is free to use MenuUtils
module, even in commercial code. In case of commercial use I would
like to know this in advance (I could than provide you with the latest
release). You can always contact me if you found some bug, or when
having other suggestions.

         To contact the author of MenuUtils, please write to:

                                        RUSSIA
                                        115541
                                        Moscow
                                        Kavkazsky boulevard, 29
                                        Bld. 1, Flat 107
                                        Alex Petrov

                         E-mail: [e-mail]
                                 [e-mail]

                         FIDO :  2:5020/104.13

                          phone: [phone]
                          fax  : [phone]